docs(platform): design self-host stack supervision — keep pgid, decline Quadlet (RIG-3239) - #872

…y (RIG-3239)

Fold the single-review-of-record (ReviewStackSupervision872) on the
stack-supervision design: 1 high, 5 medium, 4 low. All load-bearing Go
citations were re-verified at the PR head before folding.

High (lock-lifetime self-deadlock) — a genuine load-bearing fork on the
Matt-ruled DL-183 interlock, not a coordinator ruling. `up --supervise` is
the first caller to hold the state-dir lockfile with a live pid for the
stack's whole lifetime, so `DownDetached`'s live-holder guard
(`downdetached.go:74-84`) permanently refuses `down` and T1's pre-spawn
sweep self-refuses. Folded the two factual defects it exposed (the false
T2 stop-truth premise; the T1 item-4 ordering) and captured the mechanism
as OQ-6 (release-at-Ready vs mode-token guard), recommendation (b),
routed to Matt via RIG-3261 alongside OQ-5. Added a Global Constraints
lock-lifetime invariant.

Medium — OQ-4 `After=network.target` contradiction removed to match the
ruled position; `main.go:30-31` miscite corrected to `main.go:42-45`
(`defaultListenAddr`); Approach reason-#1 and OQ-5 darwin-port sites
widened from one-seam to two-seam; T1 container-supervision fork ruled
(liveness poll via `ContainerController.Exists`, unbounded-`podman wait`
rejected) and the Interfaces `Health`/`Exists` roles split; `### Resolved
decisions` promoted to `##` so the Open-Questions freeze scope holds only
OQ-4/OQ-5/OQ-6.

Low — OQ-5/OQ-6 routed to RIG-3261 in the headings; `golang.org/x/sys`
promotion indirect→direct noted with the `go.mod`/`go.sum` delta added to
T3 Produces; DL-328 row relocated from `## Infrastructure & CI` to
`## Desktop shell` (placement only, row text byte-identical); garbled
"non-systemd-agnostic" Alternatives prose fixed.

Additive review-fix commit atop the PR head; no `--supervise` mechanism
was ruled — OQ-6 is Matt's.

Ledger-impact: DL-328 relocated within DECISIONS.md (no text/status change)
Refs RIG-3239
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…nsistency (RIG-3239)

ReviewStackSupervision872r2 confirmed all 10 prior findings closed and the
freeze gate PASS, but flagged three new mediums of the summary-vs-detail
drift class: the prior fold corrected the OQ-6 lock-lifetime premise at its
detail sites (T1 item 4, T2 stop-truth, Global Constraints) but left two
upstream Approach summaries and one T2->T1 cross-reference carrying the
pre-fold, now-falsified claims. Fold reconciles them:

- Approach :340 counted "the one remaining fork" (OQ-5) while Open Questions
  now holds two load-bearing forks; names both OQ-5 and OQ-6.
- Approach :283-285 justified unit-aware `down` by a "undone by a restart"
  rationale the T2 fold already retracted; rewritten to the live-holder-guard
  model and flags the OQ-6 dependency.
- T2 stop-truth :648 delegated the OQ-6 behavior to "T1's smoke", which had no
  such leg; added T1 test-cycle item (5) (`down` against a supervised stack
  exits ZERO, never `ErrStackStarting`) and repointed the cross-ref.
- L1: T4 T3 tasks row still singular ("readStartTime"); widened to both
  darwin seams (`readStartTime` + `readGroupLeaderStartTime`, one shared
  encoding), matching the two-seam prose.

L2 (two ragged line-wraps, render-correct, no dropped text) deferred — not
churning a freeze-ready record for cosmetics.

Additive fold child off the bookmark tip; no DECISIONS.md change (DL-328
unchanged). Gates: markdownlint-cli2 0 errors (192 files); design-ledger-gate
OK (292 rows / 122 headers).

Refs RIG-3239
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…ation + arity (RIG-3239)

ReviewStackSupervision872r3 confirmed all 3 prior mediums + L1 genuinely
closed at both detail and summary sites, but caught two live gating mediums
of the recurring summary-vs-detail drift class in the freeze candidate:

- M1 (new, from the r2 fold): T1 test-cycle item (5) stated an
  unconditional "exits ZERO", true only under OQ-6 option (b), contradicting
  the option-discriminating T2 stop-truth bullet and T1's own child-death
  non-zero exit contract. Rewrote item (5) to be option-agnostic — never
  wedges on ErrStackStarting and the stop lands with the ruling; under (b)
  the supervising holder is signalled and exits ZERO, under (a) the lock is
  released so down signals the children and the child-death path applies.
  Anchored it in-process to the OQ-6 counterpart of
  downdetached_test.go:238 (verified at source). Being option-agnostic, it
  no longer belongs in the OQ-6 (b)-dependent inventory (:854), closing M1's
  second site.
- M2 (pre-existing, survived all three folds): the bolded
  "three interacting contract facts" summary counted a four-item list; item
  4 (pre-spawn survivor cleanup) is the most cross-referenced fact (Global
  Constraint + OQ-6-(b) site), so the miscount is load-bearing. Fixed the
  count to four.
- L1 (folded into M1's edit): item (5) now disambiguates the in-process
  harness assertion from the Linux process smoke.

Gates: markdownlint-cli2 0 errors (192 files); design-ledger-gate OK
(292 rows / 122 headers). Diff: design.md only, 11 insertions / 7 deletions.

Ledger-impact: none (DL-328 cell unchanged)
Refs RIG-3239
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…ory + reason ordinal (RIG-3239)

ReviewStackSupervision872r4 confirmed the r3 fold clean (M1 item-(5)
option-discrimination, M2 arity 3->4, L1 harness-vs-process all genuinely
closed at detail AND summary sites; no fold-introduced contradiction;
freeze gate PASS; new downdetached_test.go:238 citation verified reachable
at source), and caught two pre-existing instances of the summary-vs-detail
drift class the fold never touched:

- Medium (:858-859): the OQ-6 Recommendation's "if Matt rules (a), rewrite
  these" inventory named T1 item 4 and the T2 stop-truth bullet as
  (b)-dependent; neither is. T1 item 4's own parenthetical (:528-530) names
  (b) as the DECLINED alternative and calls the before-lock sweep "the
  option-independent fix", and Global Constraint :439-442 mandates the sweep
  "Whichever OQ-6 option lands" as a hard MUST — so the inventory instructed
  an executor who receives ruling (a) to fold away a requirement that
  survives (a) unchanged. The T2 bullet (:645-648) is option-discriminating
  and already carries both (a)/(b) branches. Second-order: the r3 fold made
  item (5) option-agnostic too, so the record now has ZERO genuinely
  (b)-dependent sites -> rewrote the sentence to state every T1/T2 site is
  option-agnostic and a ruling of (a) needs only deletion of moot (b)
  branches, not a rewrite (per the reviewer's suggested fix; NOT re-listed,
  which would re-falsify the M1 fix).

- Low (:178-179): the first "keep pgid" reason called itself a "second,
  independent reason on top of the two below" (1 on top of 2 = third); the
  Resolved-decisions row for the same argument (:867) already says "third".
  Aligned to "third".

Both folded coordinator-direct (judgment-dense frozen-record consistency).
Gates: markdownlint-cli2 0 errors (192 files); design-ledger-gate OK
(292 rows / 122 headers). Diff: design.md only, 9 ins / 3 del.

Refs RIG-3239
Ledger-impact: none (DECISIONS.md unchanged)
Co-authored-by: Matt Wilkinson <matt@rigel.build>

…ulings (RIG-3238)

Matt ruled all five Matt-fork open questions on RIG-3246 (2026-09-05), reorienting the record from "opt-in behind podman-machine, two permanent macOS backends" to "apple-container is THE macOS embedded engine":

- OQ-9 -> A: commit the mac mini on Woodpecker (ssh access provisioned); it runs the T-1 spike + T-3 live suite. GHA keeps the Linux lanes.
- OQ-10 -> sunset podman-machine on macOS; Intel + macOS <= 15 out of scope ("Apple has basically ended all support for Intel Macs"). No permanent two-backend matrix.
- OQ-11 -> vsock, mirroring the microVM's guestd forwarder (`go/internal/guestd/gateway_proxy.go:29-33`). Settles the darwin socket transport once.
- OQ-12 -> runner stays HOST-SIDE (darwin-native) driving apple-container over vsock, NOT runner-in-VM ("that's what we do for microVMs anyway too"). Overrides the older compass-local-dev in-VM ruling; agrees with embedded-revival OQ-7.
- OQ-13 -> all on apple-container, no podman: postgres + collector move onto apple-container too (T-2 ports the podman-hardwired stack shell + `ImageEnsurer`).

Folded across Approach (new ruling + spike-now/build-later sequencing), Global Constraints (interim-not-permanent podman-machine, sunset, DL-330 id), the vsock transport into the backend-plugs-in + egress sections, T-2 (postgres moves) + T-4 (runner host-side, not conditional). OQ-9..OQ-13 moved to a new Resolved decisions section; OQ-2 reframed from open transport fork to spike-confirms-the-vsock-leg. Open Questions now holds only OQ-1/OQ-3/OQ-4/OQ-5 (spike-resolvable T-1 line items) + OQ-6/OQ-7/OQ-8 (non-load-bearing). Status: Draft -> Active.

Ledger: adds DL-330 (apple-container is the macOS engine). Rebased onto current main whose ledger tail advanced to DL-328; the record's originally-claimed DL-326 was taken (session-volume clone), and the in-flight #872 claims DL-329, so this took DL-330 per the record's ID-allocation guard. The prior 5-commit review-fold stack was squashed into the base design commit during the rebase conflict-resolution (the DL-326 collision), so this reorientation lands as one fold commit atop it.

Ledger-impact: adds DL-330.
Spec-impact: none. Refs RIG-3238

Co-authored-by: Matt Wilkinson <matt@rigel.build>

…ulings (RIG-3238) (#869)

* docs(platform): freeze apple-container macOS runner — fold RIG-3246 rulings (RIG-3238)

Matt ruled all five Matt-fork open questions on RIG-3246 (2026-09-05), reorienting the record from "opt-in behind podman-machine, two permanent macOS backends" to "apple-container is THE macOS embedded engine":

- OQ-9 -> A: commit the mac mini on Woodpecker (ssh access provisioned); it runs the T-1 spike + T-3 live suite. GHA keeps the Linux lanes.
- OQ-10 -> sunset podman-machine on macOS; Intel + macOS <= 15 out of scope ("Apple has basically ended all support for Intel Macs"). No permanent two-backend matrix.
- OQ-11 -> vsock, mirroring the microVM's guestd forwarder (`go/internal/guestd/gateway_proxy.go:29-33`). Settles the darwin socket transport once.
- OQ-12 -> runner stays HOST-SIDE (darwin-native) driving apple-container over vsock, NOT runner-in-VM ("that's what we do for microVMs anyway too"). Overrides the older compass-local-dev in-VM ruling; agrees with embedded-revival OQ-7.
- OQ-13 -> all on apple-container, no podman: postgres + collector move onto apple-container too (T-2 ports the podman-hardwired stack shell + `ImageEnsurer`).

Folded across Approach (new ruling + spike-now/build-later sequencing), Global Constraints (interim-not-permanent podman-machine, sunset, DL-330 id), the vsock transport into the backend-plugs-in + egress sections, T-2 (postgres moves) + T-4 (runner host-side, not conditional). OQ-9..OQ-13 moved to a new Resolved decisions section; OQ-2 reframed from open transport fork to spike-confirms-the-vsock-leg. Open Questions now holds only OQ-1/OQ-3/OQ-4/OQ-5 (spike-resolvable T-1 line items) + OQ-6/OQ-7/OQ-8 (non-load-bearing). Status: Draft -> Active.

Ledger: adds DL-330 (apple-container is the macOS engine). Rebased onto current main whose ledger tail advanced to DL-328; the record's originally-claimed DL-326 was taken (session-volume clone), and the in-flight #872 claims DL-329, so this took DL-330 per the record's ID-allocation guard. The prior 5-commit review-fold stack was squashed into the base design commit during the rebase conflict-resolution (the DL-326 collision), so this reorientation lands as one fold commit atop it.

Ledger-impact: adds DL-330.
Spec-impact: none. Refs RIG-3238

Co-authored-by: Matt Wilkinson <matt@rigel.build>

* docs(platform): close review findings on the RIG-3246 fold (RIG-3238)

Review of the reorientation fold (0H/0M gate) returned 2H/7M/2L — the recurring summary-vs-detail drift class recurred once more (the fold rewrote the Approach/Global-Constraints/OQ-2/Resolved-decisions summary sites but left the Plan bullets, Tasks checklist, Alternatives, T-5 matrix and Problem/Intent still asserting the pre-fold framing) plus a ledger structural defect. All closed:

- H1 (ledger): the DL-330 row was orphaned — the DL-325 blockquote note + blank line terminated the markdown table, so DL-330 rendered as a paragraph, not a citable row (design-ledger-gate is blind to it; GitHub's renderer confirmed). Re-emitted the `| ID | Decision | Status | Record |` header pair before DL-330 (the First-turn-delivery precedent). Verified via the GitHub markdown API: DL-330 now renders as `<td>DL-330</td>`.
- H2 + M6 (spike legs): rewrote T-1(b) from the raw-AF_UNIX-bind-mount experiment to the ruled vsock experiment (VZVirtioSocketDevice reachable through the container CLI, guestd-style forwarder, connect+round-trip over vsock); re-enumerated the Tasks checklist to all six legs with the vsock transport.
- M1 (T-1c): dropped the two-way "whatever transport gets selected" framing; the vsock hop is out-of-band of the guest netfilter so no gateway carve-out, re-confirming the OQ-2/OQ-3 coupling is dissolved.
- M2 (Alternatives): the OQ-7 socket-transport hazard is dissolved by the ruled vsock transport, not a virtiofs coin-flip.
- M3 (T-5): the flip begins podman-machine's macOS sunset; Intel/macOS <= 15 are out of scope, not a permanent second supported arm.
- M4/M5 (Problem/Intent + self-description): past-tensed the central fork (ruled in Approach); the record carries Matt's ruling + an adoption plan whose BUILD is spike-gated, not a recommendation.
- M7 (OQ-5): re-tagged [non-load-bearing] and dropped the Matt-confirm request — the one-version-floor dependency is intrinsic to the committed RIG-3246 direction, mitigated by the version-floor probe + pinned-floor policy.
- L1/L2: stray `**`; aligned T-1(f) register with T-4.

Verified: markdownlint 0, design-ledger-gate OK (296 rows), residual-drift scan clean, DL-330 renders as a real table cell.

Re-review confirmed all 11 prior findings closed + DL-330 a real table row, but caught 2 new mediums of the same drift class (summary/detail split) + 1 low, now also closed:

- N1 (OQ-3 body): OQ-3 still stated "the ruleset must not sever the guest↔host gateway hop the agent socket rides" — the pre-vsock IP-hop premise the ruled transport dissolves. Dropped the agent-socket leg (it rides vsock, out-of-band of netfilter, no carve-out); kept the DNS + nftables-support + arming-order legs (genuinely still unverified).
- N2 (OQ-5): the version-floor probe was cited as (T-1(e)), but that leg is timings/stability — the probe is T-2's `VerifyAppleContainerSupport`. Corrected to (T-2).
- L-N2: re-flowed the ragged wrap in the Alternatives paragraph. (L-N1, the two-tables-under-one-heading shape, is the only structurally correct H1 fix — left as-is per the reviewer.)

Ledger-impact: none (DL-330 unchanged in substance; the header-pair fix makes it render as a row).
Spec-impact: none. Refs RIG-3238

Co-authored-by: Matt Wilkinson <matt@rigel.build>

---------

Co-authored-by: Matt Wilkinson <matt@rigel.build>